home *** CD-ROM | disk | FTP | other *** search
/ Compendium Deluxe 1 / LSD Compendium Deluxe 1.iso / sys / c / reqask.doc < prev    next >
Encoding:
Text File  |  1993-02-02  |  10.3 KB  |  300 lines
  1.  
  2.                                                        Wuerzburg, 03-Feb-93
  3.  
  4.                                 ReqASK 1.0
  5.  
  6.                            English Documentation
  7.  
  8.  
  9.  
  10. Disclaimer
  11. ~~~~~~~~~~
  12.  
  13.   ReqASK  (and  all files related to it) are Copyright 1993 by Marc Heuler,
  14. all rights reserved.  This program is Shareware.  If you like it and use it
  15. a lot, please pay the Shareware fee of 10.- DM (or $7 US).
  16.  
  17.   You may freely distribute ReqASK by these conditions:
  18.  
  19.         · Don't take *anything* for copying, except the cost of the media
  20.           itself
  21.  
  22.         · Do not change any of the files related to this program
  23.  
  24.         · Distribute all related files at once, packed into one archive
  25.  
  26.         · German PD-Serials are not allowed to distribute this program
  27.  
  28.         · Fred Fish with his famous software library does *not* have to
  29.           care about all these conditions.
  30.  
  31.   This  program  is  "AS  IS",  which  means you use it at your *own* risk.
  32. There's  no warranty at all.  However, we've tested it a lot and think it's
  33. reliable.
  34.  
  35.   Many  thanks  to  Michael  Herold,  who  helped  me both beta-testing the
  36. program and creating the AmigaGuide documentation.
  37.  
  38.  
  39.  
  40. What is ReqASK?
  41. ~~~~~~~~~~~~~~~
  42.  
  43.   ReqASK  is a powerful mouse-driven replacement for the shell command ASK.
  44. It's  supposed  to  prompt the user with several choices.  According to the
  45. result,  a  certain  action  can be taken.  Unlike similar programs, ReqASK
  46. gives you a large palette of features to customize to fit your needs.
  47.  
  48.   This  program  supports  and requires Kickstart 2.04 (v37) or higher.  It
  49. also requires "reqtools.library" (by Nico François) v38 or higher, which is
  50. available by FD (for example on Fish-Disk 794).
  51.  
  52.  
  53.  
  54. Usage
  55. ~~~~~
  56.  
  57.   ReqASK is a CLI/Shell tool, therefore it doesn't make real sense to start
  58. it from Workbench.
  59.  
  60.    BODY/K
  61.  
  62.           This  is  the body text of your requester.  If you leave out this
  63.         option,  all  others will be ignored and an About requester will be
  64.         shown.
  65.  
  66.           You  may use all common control sequences in this string, such as
  67.         *N  for a new line, or *" for quotes.  Look up your AmigaDOS manual
  68.         for more detailed information.
  69.  
  70.    GADGET/K
  71.  
  72.           This  option  is  used  to  define  the gadgets' texts.  Separate
  73.         several  choices  by  the  "|"  sign.   Examples  are  "Yes|No", or
  74.         possibly "Yes|Maybe|No".  Maximum number of choices is 100.
  75.  
  76.           If you like your requester keyboard-controllable, use underscores
  77.         to indicate the corresponding keys to press ("_Yes|_Maybe|_No").
  78.  
  79.           Please  note  that  the  requester  cannot be put up, if you don't
  80.         specify  minimum one of the options GADGET, IDCMP, and TIMEOUT.  You
  81.         won't  be  able to answer such a requester, therefore it doesn't pop
  82.         up.
  83.  
  84.    TITLE/K
  85.  
  86.           This is the requester's title.  If you don't specify this option,
  87.         the title will be either "Information" (if less than 2 gadgets), or
  88.         "Request" (two or more choices).
  89.  
  90.    VAR=VARIABLE/K
  91.  
  92.           Specify   an  environment  variable  here.   The  result  of  the
  93.         requester  will  be  stored  in  the  variable.  The default result
  94.         variable is called "REQASK".
  95.  
  96.    GLOBAL/S
  97.  
  98.           If  you  specify this keyword, the result variable will be global
  99.         (not limited to the current process).
  100.  
  101.    TIME=TIMEOUT/N/K
  102.  
  103.           This  is  one  of the main features of ReqASK.  You may specify a
  104.         timelimit  after  which  the requester will automatically close (if
  105.         the user didn't select any choice already).  The unit is seconds.
  106.  
  107.           Please  note  that  the  requester  cannot be put up, if you don't
  108.         specify  minimum one of the options GADGET, IDCMP, and TIMEOUT.  You
  109.         won't  be  able to answer such a requester, therefore it doesn't pop
  110.         up.
  111.  
  112.    SCREEN=PUBSCREENNAME/K
  113.  
  114.           Name  of  a public screen to open the requester on.  If you don't
  115.         specify this option, the requester will open on your Default Public
  116.         Screen.  Usually this is the Workbench screen.
  117.  
  118.    FRONT=SCREENTOFRONT/K
  119.  
  120.           If  you set this option to "YES" or "ON", the screen on which the
  121.         requester  opens  will  pop  to front.  After the user made his/her
  122.         selection, the screen will go back saftely to where it was before.
  123.  
  124.           To disable this option, select "NO" or "OFF".
  125.  
  126.           If  you  don't  use  this  keyword  at all, the default behaviour
  127.         configured in reqtools' preferences editor will take place.
  128.  
  129.    CENTER=NOCENTERTEXT/S
  130.  
  131.           ReqASK automatically centers the body text of your requester.  If
  132.         you don't like this, disable it by mentioning this keyword.
  133.  
  134.    DEFRES=DEFAULTRESPONSE/N/K
  135.  
  136.           If  you  have  several gadgets in your requester, the leftmost is
  137.         handled  as  'positive'  -  as default response.  It is selected by
  138.         simply  pressing  the  Return  key.  To have another (not leftmost)
  139.         gadget be the default response, specify the gadget's number here.
  140.  
  141.           The default response will be rendered in bold letters.
  142.  
  143.    FONT/K
  144.  
  145.           Your  requester  normally  uses the screen font for rendering all
  146.         texts.   To  use  another  font,  simply state the fontname and the
  147.         desired  size.   For  example FONT="courier.font 13" will result in
  148.         using  the  courier  font, size 13.  Note to surround font name and
  149.         size with quotes.
  150.  
  151.    POS=POSITION/K
  152.  
  153.           Like  the  SCREENTOFRONT  option  before, leaving out this option
  154.         will  lead  to  behave  like  configured  in  reqtools' preferences
  155.         editor.   Use  this  option to change the default behaviour of your
  156.         requester.  You may specify one of the following possibilities:
  157.  
  158.                 POINTER         The requester will pop up at the
  159.                                 current mouse position
  160.  
  161.                 CENTERSCREEN    The requester will be centered in
  162.                                 the visible part of your screen
  163.  
  164.                 TOPLEFTSCREEN   The requester will appear at the
  165.                                 top left edge of the visible part
  166.                                 of your screen
  167.  
  168.    LEFT=POS_LEFTOFFSET/N/K
  169.  
  170.           If  you  specified  a  certain  requester  position  (other  than
  171.         POINTER),  you  may  set a horizontal offset  to that position.  If
  172.         you  don't specify it, the default out of the reqtools' preferences
  173.         editor will be used.
  174.  
  175.    TOP=POS_TOPOFFSET/N/K
  176.  
  177.           If  you  specified  a  certain  requester  position  (other  than
  178.         POINTER),  you  may set a vertical offset to that position.  If you
  179.         don't  specify  it,  the  default  out of the reqtools' preferences
  180.         editor will be used.
  181.  
  182.    RETURN=NORETURNKEY/S
  183.  
  184.           If you don't want your requester to be answerable with the Return
  185.         key, specify this option.
  186.  
  187.    LAMG=LAMIGAONLY/S
  188.  
  189.           For  functions  which may cause serious damages you might wish to
  190.         disable  the abbreviated selection of choices.  Set this keyword to
  191.         disable  these.   You  then  have to press the left Amiga key along
  192.         with "B" or "V" for positive or negative selection.
  193.  
  194.    IDCMP/K
  195.  
  196.           This  is  another  wonderful  feature of ReqASK.  You may specify
  197.         certain IDCMP flags which cause the requester to end automatically.
  198.         You can choose one or more of these IDCMP flags:
  199.  
  200.                 DISKINSERTED    A disk was inserted into any drive
  201.  
  202.                 DISKREMOVED     A disk was taken out of any drive
  203.  
  204.                 INACTIVEWINDOW  The requester window got deactivated
  205.  
  206.           Please  note  that  the  requester  cannot be put up, if you don't
  207.         specify  minimum one of the options GADGET, IDCMP, and TIMEOUT.  You
  208.         won't  be  able to answer such a requester, therefore it doesn't pop
  209.         up.
  210.  
  211.    BEEP=DISPLAYBEEP/S
  212.  
  213.           If you start requesters from background processes, you might wish
  214.         be  to  notified  about  a  requester.   To  DisplayBeep() when the
  215.         requester pops up, specify this option.
  216.  
  217.  
  218.  
  219. ReqASK Result
  220. ~~~~~~~~~~~~~
  221.  
  222.   The  result of ReqASK is split into two parts.  One is the CLI Returncode
  223. which  indicates  success or failure of ReqASK.  A Returncode of 0 means no
  224. errors occured, while a Returncode of 20 states errors (normally along with
  225. a more detailed error description to StdOut).
  226.  
  227.   The second and more important part of the result (in case of no failures)
  228. is  the Result Variable holding information about which gadget the user did
  229. choose.   A  value of 0 always indicates the right-most (FALSE) gadget, the
  230. others are numbered from 1 to N, heading from left to right.
  231.  
  232.   There  are  two  special  values.  A result of 100 means, the user didn't
  233. react on the requester until the timelimit expired, the value 101 indicates
  234. the requester was closed by an IDCMP event.
  235.  
  236. NOTE:   In  case of an error (Returncode = 20) the result variable will not
  237.         be touched by the program.
  238.  
  239.  
  240.  
  241. Examples
  242. ~~~~~~~~
  243.  
  244.   Simply type these examples into your shell to see what happens:
  245.  
  246. ReqASK
  247.  
  248. ReqASK BODY="This requester reminds you*Nabout your Grandma's birthday" GADGET="_Okay" TITLE="Don't forget"
  249.  
  250. ReqASK BODY="Current system time is*N`Date`" TIME=10
  251.  
  252. ReqASK BODY="Remove ALF2-Bootdisk now!" IDCMP=DISKREMOVED POS=CENTERSCREEN
  253.  
  254.  
  255.  
  256. History
  257. ~~~~~~~
  258.  
  259. ReqASK 1.0  03-Feb-93  First public release
  260.  
  261.  
  262.  
  263. Future enhancements
  264. ~~~~~~~~~~~~~~~~~~~
  265.  
  266.   Only  thing  I  plan  to  add to ReqASK so far is ARexx support.  This is
  267. useful  when  for example playing samples in conjunction with UPD while the
  268. requester pops up.
  269.  
  270.   On the other hand I think about expanding the series of ASK commands, for
  271. example  a  very  powerful  FileASK,  which  asks  you  for files (via file
  272. requester).   Or  ViewASK,  which gives you a large amount of choices via a
  273. listview gadget.
  274.  
  275.   There  are many small things to be done.  If you like to see them, please
  276. support my work by paying the Shareware fee.
  277.  
  278.  
  279.  
  280. Contacting the author
  281. ~~~~~~~~~~~~~~~~~~~~~
  282.  
  283.   To  send  bug-reports,  ideas,  complaints,  and of course your Shareware
  284. registration fee of 10.- DM (or $7 US), contact me at:
  285.  
  286.         UUCP eMail: marc@aargh.adsp.sub.org
  287.  
  288.         ZNet eMail: marc%aargh.incubus@aworld.zer
  289.  
  290.         Snail Mail: Marc Heuler
  291.                     Stephan Str. 6
  292.                     8700 Wuerzburg
  293.                     GERMANY
  294.  
  295.   Don't forget to pay the Shareware fee if you use ReqASK a lot!
  296.  
  297.  
  298.                                                                        Marc
  299.  
  300.